التحكم المجدول عبر MQTT

تلميح

التحكم المجدول عبر MQTT مخصص للرسائل المجدولة مسبقًا. للتحكم المباشر، راجع التحكم المباشر عبر MQTT بدلاً من ذلك.

ستساعدك هذه الدليل على تكوين MQTT على SmartgridOne Controller الخاص بك للتحكم عن بُعد ورصد تركيبات البطاريات والألواح الشمسية.

ما تحتاجه

1. SmartgridOne Controller مع اتصال بالإنترنت.
2. بيانات اعتماد MQTT: يمكن طلب ذلك عن طريق إرسال بريد إلكتروني إلى support@eniris.be.
3. بيئة تطوير Python (أو أي عميل MQTT آخر). يستخدم هذا الدليل مثالًا بسيطًا مكتوبًا بلغة Python لمساعدتك على البدء مع MQTT وإرسال الأوامر. نوصي باستخدام Python لسهولة الاستخدام، ولكن أي عميل MQTT آخر مدعوم.

معلومات إضافية

MQTT هو بروتوكول اتصال سريع عبر الإنترنت. إنه نظام رسائل نشر/اشتراك، مما يسمح باتصال مباشر بين جهازك وSmartgridOne Controller. يتم تصنيف الأصول الخاصة بك إلى مجموعات من الطاقة الشمسية، والبطارية، والمركبة الكهربائية، وأنظمة التدفئة والتهوية وتكييف الهواء. حاليًا، يتيح هذا التكامل التحكم على مستوى المجموعة، وليس على مستوى الجهاز.

الإعداد الأولي (نقطة البداية للمستخدمين الجدد)

لدي SmartgridOne Controller أود إعدادها للتحكم عن بُعد عبر MQTT.

1. تحقق من الشبكة الخاصة بك

تأكد من أن الشبكة الخاصة بك تسمح بمرور حركة مرور MQTT عبر المنفذ 1883. يمكنك القيام بذلك باستخدام الأمر:

nc -zv mqtt.eniris.be 1883

عندما يكون هذا الأمر غير متاح، يمكنك بدلاً من ذلك تحميل وتنفيذ هذا الكود بلغة بايثون.

عند الشك، استشر مهندس الشبكة الخاص بك أو استخدم مؤقتًا نقطة اتصال 4G/5G الخاصة بهاتفك عند حدوث أخطاء في الاتصال.

ملاحظة

عند عدم إمكانية الوصول إلى المنفذ 1883 من شبكتك، نقدم نسخة احتياطية على المنفذ 80. يمكن تكوين ذلك في عميل MQTT الخاصة بك في خطوة لاحقة في هذا الدليل.

2. إضافة الأجهزة الخاصة بك

قم بتسجيل الدخول إلى واجهة التكليف وتأكد من أن الأجهزة قد أضيفت إلى SmartgridOne Controller.

3. إضافة إشارة خارجية عبر MQTT

4. تفعيل إشارة MQTT عن بُعد

حدد جميع الأجهزة التي ترغب في تضمينها في التحكم عن بُعد عبر MQTT.

5. تمت إضافة الإشارة عن بُعد

تم الآن تفعيل واجهة التحكم عن بُعد عبر MQTT على SmartgridOne Controller.

نحن الآن جاهزون لإرسال بعض الأوامر الأساسية باستخدام مثال بسيط. تخبرك عمود الحالة إذا كان هناك أي أمر نشط.

نص البرنامج التجريبي بلغة بايثون

سيكون بداية جيدة أن تختبر تكاملتك الجديدة مع مثال بسيط.

يقوم كود الاختبار هذا بعمل بسيط يتمثل في إرسال الجدول الزمني التالي باستمرار:

• البطارية: يتم شحنها عند 5 كيلو واط لمدة 15 دقيقة كل 10 دقائق
• الطاقة الشمسية: ضبط الطاقة على 0 كيلو واط لمدة ساعة كل 30 دقيقة

تستجيب SmartgridOne Controller برسالة تأكيد تحتوي على معرف الجدول الزمني الفريد، أو رسالة خطأ.

ثم نقوم بالحصول على الجدول الزمني التالي لكلا نوعي الأجهزة، مؤكدين أن الأمر كان ناجحًا.

يرجى تحميل الملف أدناه في IDE المفضل لديك بلغة Python. أدخل رقمك التسلسلي وبيانات اعتماد MQTT ثم نفذ السكربت:

عند نجاح ما سبق، يمكنك الاستمرار في إرسال أنواع أخرى من الرسائل. جميع الرسائل موصوفة أدناه.

وثائق MQTT لإرسال الأوامر

تستعرض هذه section تنسيق رسائل MQTT ومتطلبات الحمولة لإعداد التحكم المجدول للأجهزة ضمن شبكة SmartgridOne Controller.

مواضيع MQTT

• موضوع الاشتراك: standard1/rp_one_s/remoteScheduleMetrics/<controller SN>
• موضوع التغذية الراجعة: standard1/outbound/remoteScheduleMetrics/feedback/<controller SN>

حيث يجب استبدال <controller SN> برقم السيريال الفعلي لـ SmartgridOne Controller الذي تنوي التحكم به.

أنواع رسائل MQTT

1. تعيين الجدول الزمني (set_schedule)

ينشئ جدولًا زمنيًا جديدًا لنوع جهاز.

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "set_schedule",
    "fields": {
        "device_type": "<Device Type>",
        "node_id": "<Node ID>" (اختياري),
        "start_time": <Unix Timestamp>,
        "end_time": <Unix Timestamp>,
        "policy": "<Policy>",
        "power_setpoint_w": <Setpoint in watts>,
        "remove_overlap": <True/False> (اختياري) (الافتراضي=False),
        "tag": <Tag String> (اختياري) (الافتراضي=None)
    }
}

الرد (نجاح):

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "set_schedule_ack",
        "state": {
            "schedule_id": <Schedule ID>,
            "deleted_ids": <Schedulde IDs deleted if remove_overlap=True>,
            "tag": <Tag String> (الافتراضي=None)
        },
        "responseCode": 0
    }
}

2. تعيين الجداول الزمنية (set_schedules)

ينشئ جداول زمنية جديدة متعددة.

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "set_schedules",
    "fields": 
        "0": {
            "device_type": "<Device Type>",
            "node_id": "<Node ID>" (اختياري),
            "start_time": <Unix Timestamp>,
            "end_time": <Unix Timestamp>,
            "policy": "<Policy>",
            "power_setpoint_w": <Setpoint in watts>,
            "remove_overlap": <True/False> (اختياري) (الافتراضي=False)
        }, 
        "1": {
            "device_type": "<Device Type>",
            "node_id": "<Node ID>" (اختياري),
            "start_time": <Unix Timestamp>,
            "end_time": <Unix Timestamp>,
            "policy": "<Policy>",
            "power_setpoint_w": <Setpoint in watts>,
            "remove_overlap": <True/False> (اختياري) (الافتراضي=False)
        }, 
        ...
}

الرد (نجاح):

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "set_schedules_ack",
        "state": {
            "schedule_ids": <Schedule IDs>,
            "deleted_ids": <Schedulde IDs deleted if remove_overlap=True>
        },
        "responseCode": 0
    }
}

3. الحصول على الجدول الزمني (get_schedule)

يسترجع جدولًا زمنيًا محددًا حسب المعرف.

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "get_schedule",
    "fields": {
        "id": <Schedule ID>
    }
}

الرد:

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "get_schedule_ack",
        "state": <Schedule>,
        "responseCode": 0
    }
}

4. الحصول على الجدول النشط (get_active_schedule)

يسترد الجدول النشط حاليًا لنوع الجهاز.

{
    "extraTags": {
{
    "nodeId": "<Controller SN>_site_0"
},
"time": <Unix Timestamp>,
"message_type": "get_active_schedule",
"fields": {
    "device_type": "<Device Type>",
    "node_id": "<Node ID>" (اختياري)
}
}
{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "get_active_schedule_ack",
        "state": <Schedule>,
        "responseCode": 0
    }
}

#### 5. احصل على الجدول التالي (`get_next_schedule`)
يسترجع الجدول القادم لجهاز معين.

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "get_next_schedule",
    "fields": {
        "device_type": "<Device Type>",
        "node_id": "<Node ID>" (اختياري)
    }
}
{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "get_next_schedule_ack",
        "state": <Schedule>,
        "responseCode": 0
    }
}

#### 6. احصل على الجداول (`get_schedules`)
يسترجع جميع الجداول لتاريخ معين.

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "get_schedules",
    "fields": {
        "date": "<Date String of Format dd/mm/yyyy>"
    }
}
{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "get_schedules_ack",
        "state": {
            "schedules": [<Schedule>, ...]
        },
        "responseCode": 0
    }
}

#### 7. احصل على الجداول المستقبلية (`get_future_schedules`)
يسترجع جميع الجداول المستقبلية.

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "get_future_schedules",
    "fields": {}
}
{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "get_future_schedules_ack",
        "state": {
            "schedules": [<Schedule>, ...]
        },
        "responseCode": 0
    }
}

#### 8. إزالة الجدول (`remove_schedule`)
يزيل جدولاً محدداً بواسطة ID.

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "remove_schedule",
    "fields": {
        "id": <Schedule ID>
    }
}
{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "remove_schedule_ack",
        "state": "تمت إزالة الجدول <Schedule ID> بنجاح",
        "responseCode": 0
    }
}

#### 9. احصل على تغذية الموقع (`get_feedback`)
يسترجع تغذية تفصيلية حول حالة النظام.

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "get_feedback",
    "fields": {
        "device": <Device (node) level>
    }
}

Response (Success): 

[هيكل بيانات التغذية الراجعة](/External%20Signals/MQTT/eniris-mqtt/#mqtt-feedback-payload-structure/)

#### 10. طوبولوجيا الموقع (`get_toplogy`)
يحصل على طوبولوجيا الموقع.

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "get_topology",
    "fields": {}
}
{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "get_topology_ack",
        "state": {
            "nodeId": <nodeId>,
            "nodeType": <nodeType>,
            "children": [{<ChildObject>}]
            },
        "responseCode": 0
    }
}

#### تنسيق استجابة الجدول القياسي

{
    "id": <Schedule ID>,
    "device_type": "<Device Type>",
    "node_id": "<Node ID>" (اختياري),
    "start_time": <Unix Timestamp>,
    "end_time": <Unix Timestamp>,
    "policy": "<جدول السياسة>",
    "power_setpoint_w": <تحديد الطاقة بالواط>,
    "created_at": <Unix Timestamp>
}

### أنواع المكونات والسياسات
للحصول على تفاصيل حول المكونات المتاحة والسياسات التي يمكن جدولتها، يرجى الرجوع إلى قسم [المكونات والسياسات MQTT](/External%20Signals/MQTT/eniris-mqtt/#components-and-policies) في وثائق التحكم MQTT المباشرة.

يمكن إرسال الجداول المحددة لجهاز معين باستخدام حقل `node_id` الاختياري، والذي يشير إلى ID العقدة للجهاز القابل للتحكم.

### معالجة الأخطاء
يمكن أن ترجع جميع الرسائل استجابة بخطأ مع `responseCode: 1` عند حدوث خطأ:

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "<Message Type>_ack",
        "error": <Error Body>,
        "responseCode": 1
    }
}

عند حدوث خطأ غير ذي صلة، سيكون نوع الرسالة هو (`general_error`).

الأخطاء الشائعة تشمل:
- تداخل الجدول مع الجداول الموجودة
- نطاق زمني غير صالح
- نوع الجهاز غير موجود
- ID الجدول غير موجود
- سياسة غير صالحة لنوع الجهاز

### قواعد إدارة الجدول
1. قواعد التداخل
    - لا يمكن أن تتداخل الجداول لنفس نوع الجهاز
    - لا يمكن أن تتداخل الجداول لنفس الجهاز
    - لا يمكن أن تتداخل الجداول للجهاز ونوع الجهاز ذاته
    - سيتم حذف الجداول الحالية المتداخلة إذا تم تعيين المتغير `remove_overlap` إلى `True` عند إنشاء جدول جديد.
2. يجب أن يحتوي كل جدول على:
   - نوع جهاز صالح
   - وقت بداية (طابع زمني Unix)
   - وقت نهاية (طابع زمني Unix)
   - سياسة (تطابق السياسات المتاحة لنوع الجهاز)
   - نقطة إعداد الطاقة (للسياسات التي تتطلب ذلك)
3. يجب أن يكون وقت البدء قبل وقت الانتهاء
4. إذا كان وقت البدء في الماضي، فسيتم تغييره تلقائيًا لبدء الآن
5. يمكن حذف الجداول فقط إذا لم تبدأ بعد. **لا يمكن حذف الجداول النشطة.**
6. يمكن تعيين الجداول لأنواع أجهزة مختلفة بشكل مستقل
7. يقوم النظام تلقائيًا بتطبيق السياسة المناسبة عند تفعيل الجدول